home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 451-475 / disk_457 / cmanual / acm4.lzh / Appendices / Functions.doc < prev    next >
Text File  |  1991-01-27  |  73KB  |  2,445 lines
  1. B   FUNCTIONS
  2.  
  3. B.1  INTRODUCTION
  4.  
  5. Here is the complete list of all functions described in the
  6. Manual.
  7.  
  8.  
  9.  
  10. B.2  INTUITION LIBRARY
  11.  
  12. The Intuition Library must have been opened before you may call
  13. these functions, and you will probably have to include the file
  14. "intution.h". For example:
  15.  
  16. #include <intuition/intuition.h>
  17.  
  18. struct IntuitionBase *IntuitionBase;
  19.  
  20. main()
  21. {
  22.   /* Open the Intuition Library: */
  23.   IntuitionBase = (struct IntuitionBase *)
  24.     OpenLibrary( "intuition.library", 0 );
  25.   
  26.   if( IntuitionBase == NULL )
  27.     exit(); /* Could NOT open the Intuition Library! */
  28.  
  29.  
  30.   ... ...
  31.  
  32.  
  33.   /* Close the Intuition Library: */
  34.   CloseLibrary( IntuitionBase );
  35. }
  36.  
  37.  
  38. AddGadget()
  39.  
  40.   This function adds a gadget to the gadget list.
  41.  
  42.   Synopsis: result = AddGadget( window, gadget, position );
  43.   
  44.   result:   (long) The actual position of the gadget when it
  45.             has been added.
  46.  
  47.   window:   (struct Window *) Pointer to the window, to which
  48.             the gadget should be added.
  49.  
  50.   gadget:   (struct Gadget *) Pointer to the gadget which will
  51.             be added.  
  52.  
  53.   position: (long) Position in the gadget list. (Starts from
  54.             zero). Eg:
  55.               0 -> Before all other gadgets.
  56.               1 -> After the first gadget, but before the
  57.                    second.
  58.               If a too big value is entered (or -1), the gadget
  59.               will be placed last in the list.
  60.  
  61.  
  62.   Important, after your program has added the necessary
  63.   gadgets, you need to call the function RefreshGadgets() in
  64.   order to see your changes. You may add (or take away) several
  65.   gadgets, but when you are finished you must call that
  66.   function.
  67.  
  68.  
  69.  
  70. AddVSprite()
  71.  
  72.   This function will add a VSprite to the VSprite list.
  73.  
  74.   Synopsis: AddVSprite( vsprite, rp );
  75.  
  76.   vsprite:  (struct VSprite *) Pointer to an initialized
  77.             VSprite structure.
  78.  
  79.   rp:       (struct RastPort *) Pointer to the RastPort.
  80.  
  81.  
  82.  
  83. AllocRemember()
  84.  
  85.   This function allocates both memory (same as AllocMem), but
  86.   will also allocate space for a Remember structure which are
  87.   initialized with the size of the allocated memory, and a
  88.   pointer to that memory. Each time the program allocates
  89.   memory with this function, the Remember structures are linked
  90.   together.
  91.   
  92.   Since the Remember structures contains all necessary
  93.   information about the memory, and are linked together, all
  94.   memory can be deallocated with one single function call
  95.   (FreeRemember()).
  96.  
  97.   Synopsis: memory = AllocRemember( remember, size, type );
  98.  
  99.   memory:   (char *) Pointer to the new allocated memory, or
  100.             NULL if no memory could be allocated. Remember!
  101.             Never use memory which you have not successfully
  102.             allocated.
  103.  
  104.   remember: (struct Remember **) Address of a pointer to a
  105.             Remember structure. Before you call the
  106.             AllocRemember() function for the first time you
  107.             should set this pointer to NULL. (Note that it is
  108.             a pointer to a pointer!)
  109.  
  110.   size:     (long) The size (in bytes) of the memory you want.
  111.             (AllocMem() always allocates memory in multiples of
  112.             eight bytes. So if you only ask for 9 bytes, Exec
  113.             would actually give you 16 Bytes (2*8).)
  114.  
  115.   type:     (long) You need to choose one of the three
  116.             following types of memory (see chapter 0
  117.             INTRODUCTION for more information about Chip and
  118.             Fast memory):
  119.  
  120.             MEMF_CHIP   Chip memory. This memory can be
  121.                         accessed by both the main processor, as
  122.                         well as the Chips. Graphics/Sound data
  123.                         MUST therefore be placed in Chip memory.
  124.                         If it does not matter what type of 
  125.                         memory you get (Fast or Chip), you
  126.                         should try to allocate Fast memory
  127.                         before you allocate Chip memory. (Chip
  128.                         memory is more valuable than Fast
  129.                         memory.)
  130.  
  131.             MEMF_FAST   Fast memory. This memory can only be
  132.                         accessed by the main processor.
  133.                         (Graphics and Sound data can NOT be
  134.                         stored in Fast memory, use Chip memory.)
  135.                         This memory is normally a little bit
  136.                         faster than Chip memory, since only the
  137.                         main processor is working with it, and
  138.                         it is not disturbed by the Chips.
  139.  
  140.             MEMF_PUBLIC If it does not matter what type of
  141.                         memory you get (you do not intend to
  142.                         use the memory for Graphics/Sound data),
  143.                         you should use Fast memory. However,
  144.                         all Amigas do not have Fast memory,
  145.                         since you need to by a memory expansion
  146.                         in order to get it. If want to tell
  147.                         Exec that you would like to use Fast
  148.                         memory if there is any, else use Chip
  149.                         memory, you should ask for MEMF_PUBLIC.
  150.  
  151.             If you want the allocated memory to be cleared
  152.             (initialized to zeros), you should set the flag
  153.             MEMF_CLEAR.
  154.  
  155.  
  156.  
  157. AutoRequest()
  158.  
  159.   This function opens a Simple requester. Intuition will
  160.   automatically activate it and take care of the response from
  161.   the user. It will return TRUE if the left gadget was
  162.   selected, and FALSE if the right gadget was selected.
  163.  
  164.   Synopsis:  result = AutoRequest( my_window, info_txt, pos_txt,
  165.                                    neg_txt, pos_IDCMP, neg_IDCMP,
  166.                                    width, height );
  167.  
  168.   my_window: (struct Window *) Pointer to a window if there
  169.              exist one, else NULL.
  170.  
  171.   info_txt:  (struct IntuiText *) Pointer to an IntuiText
  172.              structure containing the "body text".
  173.  
  174.   pos_txt:   (struct IntuiText *) Pointer to an IntuiText
  175.              structure containing the "positive text". Eg:
  176.              "TRUE", "YES", "RETRY" etc. (Optional)
  177.  
  178.   neg_txt:   (struct IntuiText *) Pointer to an IntuiText
  179.              structure containing the "negative text". Eg:
  180.              "FALSE", "NO", "CANCEL" etc.
  181.  
  182.   pos_IDCMP: (long) IDCMP flags which satisfy the "positive"
  183.              gadget. (The flag RELVERIFY is already set.)
  184.  
  185.   pos_IDCMP: (long) IDCMP flags which satisfy the "negative"
  186.              gadget. (The flag RELVERIFY is already set.)
  187.  
  188.   width:     (long) How many pixels wide the requester should
  189.              be.
  190.  
  191.   height:    (long) How many lines high the requester should
  192.              be.
  193.  
  194.   result:    (long) Boolean value. The function returns TRUE if
  195.              the positive gadget was satisfied, and FALSE if
  196.              the negative gadget was satisfied.
  197.  
  198.  
  199.  
  200. BeginRefresh()
  201.  
  202.   This function will speed up your redrawing of the window. You
  203.   should call this function before you start to refresh the
  204.   window, and only the parts that needs to be redrawn are
  205.   redrawn.
  206.  
  207.   Synopsis:  BeginRefresh( my_window );
  208.  
  209.   my_window: (struct Window *) Pointer to a Window structure
  210.              which has previously been initialized by an
  211.              OpenWindow() call.
  212.  
  213.  
  214.  
  215. ClearDMRequest()
  216.  
  217.   This function disables a Double-menu requester. The user can
  218.   not open the requester any more.
  219.   
  220.   Synopsis:     result = ClearDMRequest( my_window );
  221.  
  222.   my_window:    (struct Window *) Pointer to the Window
  223.                 structure which the requester is connected to.
  224.                 The DMRequest pointer in the Window structure
  225.                 is set to NULL.
  226.  
  227.   result:       (long) If the function could disable the
  228.                 DM-requester it returns TRUE, else (something
  229.                 went wrong, the requester is in use etc) it
  230.                 returns FALSE.
  231.  
  232.  
  233.  
  234. ClearMenuStrip()
  235.  
  236.   This function removes a menu strip from a window. Remember to
  237.   always remove the menu strip before you close the window, or
  238.   changes the menu strip.
  239.  
  240.   Synopsis:   ClearMenuStrip( my_window );
  241.  
  242.   my_window:  (struct Window *) Pointer to the window which
  243.               menu strip should be removed.
  244.  
  245.  
  246.  
  247. ClearPointer()
  248.  
  249.   This will remove the "custom" pointer, and replace it with
  250.   Intuition's default pointer.
  251.   
  252.   Synopsis:  ClearPointer( my_window );
  253.  
  254.   my_window: (struct Window *) Pointer to a Window structure
  255.              which has previously been initialized by an
  256.              OpenWindow() call.
  257.  
  258.  
  259.  
  260. CloseScreen()
  261.  
  262.   This function will close a Custom Screen which you have
  263.   previously opened.
  264.   
  265.   Synopsis:      CloseScreen( my_screen );
  266.   
  267.   my_screen:     (struct Screen *) Pointer to an already opened
  268.                  screen.
  269.  
  270.   All windows (See chapter 2 WINDOWS for more information) on
  271.   your Screen MUST have been closed before you may close the
  272.   screen. If you close a window after the screen has been
  273.   closed, the system will crash. (Not recommended.)
  274.   
  275.   If there does not exist any more screens when you close
  276.   yours, Intuition will automatically reopen the Workbench
  277.   Screen.
  278.  
  279.  
  280.  
  281. CloseWindow()
  282.  
  283.   This function will close a window you have previously opened.
  284.   Remember that you need to close all windows connected to a
  285.   screen before you may close the screen, and all opened
  286.   windows must have been closed before your program quits.
  287.  
  288.   Synopsis:  CloseWindow( my_window );
  289.  
  290.   my_window: (struct Window *) Pointer to a Window structure
  291.              which has previously been initialized by an
  292.              OpenWindow() call.
  293.  
  294.  
  295.  
  296. CloseWorkBench()
  297.  
  298.   This function will try to close the Workbench Screen if
  299.   possible. If any other programs is using the Workbench
  300.   Screen, the function can not close it. Closing the Workbench
  301.   will free some memory, and can therefore be used if your
  302.   program needs more memory.
  303.   
  304.   (Remember to reopen the Workbench Screen when your program
  305.   terminates.)
  306.  
  307.   Synopsis:      result = CloseWorkBench();
  308.   
  309.   result:        (long) A boolean value which tell us if the
  310.                  Workbench screen has been (or already was)
  311.                  closed (TRUE), or not (FALSE).
  312.  
  313.  
  314.  
  315. CurrentTime()
  316.  
  317.   This function gives the current time.
  318.  
  319.   Synopsis: CurrentTime( seconds, micros );
  320.  
  321.   seconds:  (long *) Pointer to an ULONG variable which will be
  322.             initialized with the current seconds stamp.
  323.  
  324.   micros:   (long *) Pointer to an ULONG variable which will be
  325.             initialized with the current micros stamp.
  326.  
  327.  
  328.  
  329. DisplayAlert()
  330.  
  331.   This function activates an Alert message.
  332.  
  333.   Synopsis: result = DisplayAlert( nr, message, height ); 
  334.  
  335.   nr:       (long)  Value which describes if it is a
  336.             RECOVERY_ALERT or a DEADEND_ALERT.
  337.  
  338.   message:  (char *) Pointer to an array of characters (char). It
  339.             contains the strings we want to display, and some
  340.             extra information (position etc). The string itself
  341.             is divided into substrings, which all contain
  342.             information about its position etc.
  343.           
  344.             - 2 bytes (16-bit) which are used for the x position
  345.               of the text.
  346.             - 1 byte (8-bit) which is used for the y position of
  347.               the text.
  348.             - The text string which ends with a NULL ('\0') sign.
  349.             - A Continuation byte. If it is TRUE there is another
  350.               substring after this one, else this was the last
  351.               substring.
  352.  
  353.   height:   (long) The height of the Alert box.
  354.  
  355.   result:   (long) The function DisplayAlert() returns a boolean
  356.             value. If it is a RECOVERY_ALERT and the user pressed
  357.             the left mouse button it returns TRUE else, if the
  358.             user pressed the right mouse button, it returns
  359.             FALSE. If it is a DEADEND_ALERT the function will
  360.             immediate return FALSE.
  361.  
  362.  
  363.  
  364. DisplayBeep()
  365.  
  366.   This function flashes the screen's colours. Can be used
  367.   whenever you want to catch the user's attention.
  368.  
  369.   Synopsis: DisplayBeep( screen );
  370.    
  371.   screen:   (struct Screen *) Pointer to the screen, which
  372.             colours you want to flash. If you have not opened
  373.             a screen yourself (you are using the Workbench
  374.             Screen), you can find a pointer to that screen
  375.             in the Window structure: (my_window is a pointer
  376.             to an opened window)
  377.             DisplayBeep( my_window->WScreen );
  378.  
  379.  
  380.  
  381. DoubleClick()
  382.  
  383.   This function checks if the user double-clicked on one of the
  384.   mouse buttons. You give the function the current as well as
  385.   the previous time when the button was pressed, and it will
  386.   check the preferences and return TRUE if the two button
  387.   events happened within the time limit.
  388.  
  389.   Synopsis: double = DoubleClick( sec1, mic1, sec2, mic2 );
  390.  
  391.   double:   (long) If the two button events happened within the
  392.             current time limit, the function will return TRUE,
  393.             else it will return FALSE.
  394.  
  395.   sec1:     (long) Time (seconds) when the button was pressed
  396.             for the first time.
  397.  
  398.   mic1:     (long) Time (micros) when the button was pressed
  399.             for the first time.
  400.  
  401.   sec2:     (long) Current time (seconds).
  402.  
  403.   mic2:     (long) Current Time (micros).
  404.  
  405.  
  406.  
  407. DrawBorder()
  408.  
  409.   This function draws the specified Borders into a RastPort
  410.   (Screen/Window).
  411.  
  412.   Synopsis:  DrawBorder( rast_port, border, x, y );
  413.  
  414.   rast_port: (struct RastPort *) Pointer to a RastPort.
  415.  
  416.              If the lines should be drawn in a window, and
  417.              my_window is a pointer to that window, you write:
  418.              my_window->RPort.
  419.           
  420.              If the lines should be drawn in a Screen, and
  421.              my_screen is a pointer to that screen, you write:
  422.              my_screen->RastPort.
  423.  
  424.   border:    (struct Border *) Pointer to a Border structure
  425.              which has been initialized with your requirements.
  426.  
  427.   x:         (long) Number of pixels added to the x coordinates.
  428.  
  429.   y:         (long) Number of lines added to the y coordinates.
  430.  
  431.  
  432.  
  433. DrawGList()
  434.  
  435.   This function will draw the VSprites into the specified
  436.   Rastport.
  437.  
  438.   Synopsis: DrawGList( rp, vp );
  439.  
  440.   rp:       (struct RastPort *) Pointer to the RastPort.
  441.  
  442.   vp:       (struct ViewPort *) Pointer to the ViewPort.
  443.  
  444.  
  445.  
  446. DrawImage()
  447.  
  448.   This function draws the specified images into a RastPort
  449.   (Screen/Window).
  450.  
  451.   Synopsis:  DrawImage( rast_port, image, x, y );
  452.  
  453.   rast_port: (struct RastPort *) Pointer to a RastPort.
  454.  
  455.              If the images should be drawn in a window, and
  456.              my_window is a pointer to that window, you write:
  457.              my_window->RPort.
  458.  
  459.              If the images should be drawn in a Screen, and
  460.              my_screen is a pointer to that screen, you write:
  461.              my_screen->RastPort.
  462.  
  463.   image:     (struct Image *) Pointer to an Image structure
  464.              which has been initialized with your requirements.
  465.  
  466.   x:         (long) Number of pixels added to the x position of
  467.              the image.
  468.  
  469.   y:         (long) Number of lines added to the y position of
  470.              the image.
  471.  
  472.  
  473.  
  474. EndRefresh()
  475.  
  476.   This function will tell Intuition that you have finished with
  477.   your redrawings. IMPORTANT! If you receive a REFRESHWINDOW
  478.   message, you must call the functions BeginRefresh() and
  479.   EndRefresh(), even if you do not want to redraw anything.
  480.   
  481.   Synopsis:  EndRefresh( my_window );
  482.  
  483.   my_window: (struct Window *) Pointer to a Window structure
  484.              which has previously been initialized by an
  485.              OpenWindow() call.
  486.  
  487.  
  488.  
  489. EndRequest()
  490.  
  491.   This function deactivates a requester which has been
  492.   activated.
  493.   
  494.   Synopsis:     EndRequest( my_requester, my_window );
  495.  
  496.   my_requester: (struct Requester *) Pointer to the Requester
  497.                 structure which will be removed.
  498.  
  499.   my_window:    (struct Window *) Pointer to the Window
  500.                 structure which the requester is connected to.
  501.  
  502.  
  503.  
  504. FreeRemember()
  505.  
  506.   This function deallocates all memory which has been allocated
  507.   by the AllocRemember() function. Note, you can deallocate all
  508.   Remember structures only, and deallocate the memory yourself,
  509.   if you want to.
  510.  
  511.   Synopsis:   FreeRemember( remember, everything );
  512.  
  513.   remember:   (struct Remember **) Address of a pointer to the
  514.               first Remember structure (initialized by the
  515.               AllocRemember() function). (Note that it is a
  516.               pointer to a pointer!)
  517.  
  518.   everything: (long) A boolean value. If everything is equal
  519.               to TRUE, all memory (both the allocated memory
  520.               and the Remember structures) are deallocated.
  521.               However, if everything is equal to FALSE, only
  522.               the Remember structures are deallocated, and you
  523.               have to deallocate the memory yourself.
  524.  
  525.  
  526.  
  527. GetDefPrefs()
  528.  
  529.   This function makes a copy of the default Preferences
  530.   structure.
  531.  
  532.   Synopsis: pref = GetPrefs( buffer, size );
  533.  
  534.   pref:     (struct Preferences *) Pointer to the default
  535.             preferences. If the function could not make a copy
  536.             of the preferences, the function returns NULL.
  537.  
  538.   buffer:   (struct Preferences *) Pointer to the memory buffer
  539.             which should be used to store a copy of the default
  540.             preferences in.
  541.  
  542.   size:     (long) The number of bytes you want to copy to the
  543.             buffer. Important, the buffer must be at least as
  544.             big as the number of bytes you want to copy.
  545.  
  546.  
  547.  
  548. GetMsg()
  549.  
  550.   This function tries to get a message from a message port.
  551.  
  552.   Synopsis:        my_message = GetMsg( my_message_port );
  553.  
  554.   my_message:      (struct Message *) Pointer to a Message
  555.                    structure, in this case a pointer to an
  556.                    IntuiMessage structure, or NULL if no
  557.                    message was collected.
  558.  
  559.   my_message_port: (struct MsgPort *) Pointer to an MsgPort. If
  560.                    you have opened a window, you can find your
  561.                    window's message port in the Window
  562.                    structure. ( my_window->UserPort )
  563.  
  564.  
  565.  
  566. GetPrefs()
  567.  
  568.   This function makes a copy of the Preferences structure.
  569.  
  570.   Synopsis: pref = GetPrefs( buffer, size );
  571.  
  572.   pref:     (struct Preferences *) Pointer to your preferences.
  573.             Same as your memory pointer (buffer), but is
  574.             returned so you can check if you got a copy or not.
  575.             If you could not get a copy of the preferences, the
  576.             function returns NULL.
  577.  
  578.   buffer:   (struct Preferences *) Pointer to the memory buffer
  579.             which should be used to store a copy of the
  580.             preferences in.
  581.  
  582.   size:     (long) The number of bytes you want to copy to the
  583.             buffer. Important, the buffer must be at least as
  584.             big as the number of bytes you want to copy.
  585.  
  586.  
  587.  
  588. InitGels()
  589.  
  590.   This function "gives" an already prepared GelsInfo structure
  591.   to the system.
  592.  
  593.   Synopsis: InitGels( head, tail, ginfo );
  594.  
  595.   head:     (struct VSprite *) Pointer to the first "dummy"
  596.             VSprite structure.
  597.  
  598.   tail:     (struct VSprite *) Pointer to the second "dummy"
  599.             VSprite structure.
  600.  
  601.   ginfo:    (struct GelsInfo *) Pointer to an initialized GelsInfo
  602.             structure.
  603.  
  604.  
  605.  
  606. ItemAddress()
  607.  
  608.   This function returns a pointer to the Menu or Item
  609.   structure which is specified by the menu number.
  610.   
  611.   Synopsis:    ItemAddress( my_menu, menu_number );
  612.   
  613.   my_menu:     (struct Menu *) Pointer to the first Menu
  614.                structure in the menu strip.
  615.  
  616.   menu_number: (USHORT) This menu number specifies a subitem/
  617.                item/menu.
  618.  
  619.  
  620. Lock()
  621.  
  622.   This function "locks" a file so no other processes may alter
  623.   the contents (SHARED_LOCK). You can even prevent other
  624.   processes to read the file (EXCLUSIVE_LOCK).
  625.  
  626.   Synopsis: lock = Lock( name, mode );
  627.  
  628.   lock:     (BPTR) Actually a pointer to a FileLock structure.
  629.  
  630.   name:     (char *) Pointer to a text string which contains
  631.             the file/directory name.
  632.  
  633.   mode:     (long) Accessmode:
  634.               SHARED_LOCK:     Other tasks may read the file.
  635.               ACCESS_READ:                 - " -
  636.               EXCLUSIVE_LOCK:  No other tasks may use this f.
  637.               ACCESS_WRITE:                - " -
  638.  
  639.  
  640.  
  641. ModifyIDCMP()
  642.  
  643.   This function changes the Window structure's IDCMPFlags
  644.   field.
  645.  
  646.   Synopsis:  ModifyIDCMP( my_window, IDCMPFlags );
  647.   
  648.   my_window:  (struct Window *) Pointer to an already opened
  649.               window.
  650.  
  651.   IDCMPFlags: (long) None or more IDCMP flags.
  652.  
  653.   If you call this function with no IDCMP flags set, the
  654.   window's IDCMP Ports will be closed. On the other hand, if
  655.   you call this function, with one or more IDCMP flags set, a
  656.   Port will be, if necessary, opened for you.
  657.  
  658.  
  659.  
  660. ModifyProp()
  661.  
  662.   This function modifies a proportional gadget's values and
  663.   knob. For example, if your program is reading files from the
  664.   disk, VertBody was maybe equal to 0xFFFF (MAXBODY) in the
  665.   beginning, but as more files are collected from the disk, you
  666.   maybe want to change the size of the knob etc. You then
  667.   simply call this function and it will change the values as
  668.   well as redraw the gadget.
  669.   
  670.   Synopsis:    ModifyProp( gadget, window, requester, flags,
  671.                horiz_pot, vert_pot, horiz_body, vert_body ); 
  672.  
  673.   gadget:      (struct Gadget *) Pointer to the proportional
  674.                gadget which should be changed and redrawn.
  675.  
  676.   window:      (struct Window *) Pointer to the window which
  677.                the proportional gadget is connected to.
  678.   
  679.   requester:   (struct Requester *) If the gadget is connected
  680.                to a requester, set this pointer to point to
  681.                that requester, else NULL. Important, if this
  682.                gadget is connected to a requester, it must be
  683.                displayed when you execute this command!
  684.  
  685.   flags:       (long) Here is the list of all flags you may
  686.                use:
  687.   
  688.                  FREEHORIZ      Set this bit if you want the
  689.                                 user to be able to move the
  690.                                 knob horizontally.
  691.  
  692.                  FREEVERT       Set this bit if you want the
  693.                                 user to be able to move the
  694.                                 knob vertically.
  695.  
  696.                  AUTOKNOB       Set this bit if you want that
  697.                                 the size of the knob to be
  698.                                 controlled by Intuition.
  699.                                 (HorizBody and VertBody
  700.                                 affects the size of the
  701.                                 Autoknob.)
  702.  
  703.                                 - If you want to use
  704.                                 Intuition's Autoknob you
  705.                                 should give GadgetRender a
  706.                                 pointer to an Image structure.
  707.                                 (You do not need to initialize
  708.                                 the Image structure since
  709.                                 Intuition takes care of it.)
  710.  
  711.                                 - If you on the other hand
  712.                                 would like to use your own
  713.                                 knob image, you give
  714.                                 GadgetRender a pointer to your
  715.                                 Image structure, which you have
  716.                                 initialized yourself.
  717.  
  718.                  PROPBORDERLESS Set this bit if you do not
  719.                                 want any border around the
  720.                                 container. 
  721.  
  722.                (See chapter 4.7 for more information.)
  723.  
  724.   horiz_pot:   (long) This variable contains the actual
  725.                (horizontally) proportional value. If the knob
  726.                should be moved 25% to the right, HorizPot
  727.                should be set to 25% of MAXPOT (0xFFFF).
  728.                (0xFFFF * 0.25 = 0x3FFF)
  729.  
  730.   vert_pot:    (long) Same as HorizPot except that this is the
  731.                vertically proportional value.
  732.  
  733.   horiz_body:  (long) Describes how much HorizPot should change
  734.                every time the user clicks inside the container.
  735.                If the volume of a melody can be between 0-63
  736.                (64 steps), HorizPot should change 1/64 each
  737.                time. The HorizBody should therefore be set to:
  738.                1/64 * MAXBODY (0xFFFF) == 3FF
  739.  
  740.                HorizBody describes also how much the user can
  741.                see/use of the entire data. For example, if you
  742.                have a list of 32 file names, and the user only
  743.                can see 8 names at one time (25%), the knob
  744.                (AUTOKNOB) should fill 25% of the container.
  745.                HorizBody should in this case be set to:
  746.                MAXBODY * 8 / 32 (25% of 0xFFFF) == 3FFFF
  747.  
  748.  
  749.   vert_body:   Same as HorizBody except that it affects
  750.                VertPot, and the vertical size of the knob
  751.                (AUTOKNOB).
  752.  
  753.  
  754.  
  755. MoveScreen()
  756.  
  757.   This function will move the screen. For the moment you may
  758.   only move it vertically.
  759.  
  760.   Synopsis:      MoveScreen( my_screen, delta_x, delta_y );
  761.  
  762.   my_screen:     (struct Screen *) Pointer to the screen which
  763.                  you want to move.
  764.  
  765.   delta_x:       (long) Number of pixels which the screen
  766.                  should move horizontally. For the moment you
  767.                  may not move a screen horizontally, set it
  768.                  therefore to 0.
  769.  
  770.   delta_y:       (long) Number of lines which the screen should
  771.                  move vertically.
  772.  
  773.  
  774.  
  775. MoveWindow()
  776.  
  777.   This function will move a window. It has the same effect as
  778.   if the user would have moved the window by using the Drag
  779.   Gadget.
  780.  
  781.   Synopsis:  MoveWindow( my_window, delta_x, delta_y );
  782.  
  783.   my_window: (struct Window *) Pointer to a Window structure
  784.              which has previously been initialized by an
  785.              OpenWindow() call.
  786.  
  787.   delta_x:   (long) Deltamovement horizontally.
  788.  
  789.   delta_y:   (long) Deltamovement vertically.
  790.  
  791.  
  792.  
  793. MrgCop()
  794.  
  795.   This function reorganizes the Copper list. This is why each
  796.   VSprite can have its own individual colour values.
  797.  
  798.   Synopsis: MrgCop( view );
  799.  
  800.   view:     (struct View *) Pointer to the View structure which
  801.             copper list should be changed.
  802.  
  803.  
  804.  
  805. OffGadget()
  806.  
  807.   This function disables a gadget (sets the GADGDISABLED bit in
  808.   the gadget structure's Flags field):
  809.   
  810.   Synopsis:  OffGadget( gadget, window, requester );
  811.  
  812.   gadget:    (struct Gadget *) Pointer to the gadget which will
  813.              be disabled.
  814.  
  815.   window:    (struct Window *) Pointer to the window that the
  816.              gadget is attached to.
  817.  
  818.   requester: (struct Requester *) If the gadget is connected to
  819.              a requester, set this pointer to point to that
  820.              requester, else NULL. Important, if this gadget is
  821.              connected to a requester, it must be displayed
  822.              when you execute this command!
  823.  
  824.  
  825.  
  826. OnGadget()
  827.  
  828.   This function enables a gadget (removes the GADGDISABLED bit
  829.   in the gadget structure's Flags field):
  830.   
  831.   Synopsis: OnGadget( gadget, window, requester );
  832.  
  833.   gadget:     (struct Gadget *) Pointer to the gadget which
  834.               will be enabled.
  835.  
  836.   window:     (struct Window *) Pointer to the window that the
  837.               gadget is attached to.
  838.   
  839.   requester:  (struct Requester *) If the gadget is connected
  840.               to a requester, set this pointer to point to that
  841.               requester, else NULL. Important, if this gadget
  842.               is connected to a requester, it must be displayed
  843.               when you execute this command!
  844.  
  845.   Remember, as long as the gadget is disabled the user can not
  846.   select it, and it will not broadcast any messages. A disabled
  847.   gadget is drawn as usual except that it "ghosted".
  848.  
  849.  
  850.  
  851. OffMenu()
  852.  
  853.   This function can disable a subitem, an item or even a whole
  854.   menu. The image or text of the disabled items etc will be
  855.   "ghosted", and the user can not select them.
  856.   
  857.   Synopsis:    OffMenu( my_window, menu_number );
  858.  
  859.   my_window:   (struct Window *) Pointer to the window which
  860.                the menu strip is connected to.
  861.   
  862.   menu_number: (USHORT) This menu number specifies what should
  863.                be disabled. Use the macros SHIFTMENU, SHIFTITEM
  864.                and SHIFTSUB to calculate the correct menu
  865.                number. If you just specify a menu, all items
  866.                to that menu will be disabled. If you specify
  867.                a menu and an item, that item will be disabled,
  868.                and so all subitems connected to it if there are
  869.                any.
  870.  
  871.  
  872.  
  873. OnMenu()
  874.  
  875.   This function can enable a subitem, an item or even a whole
  876.   menu. The image or text of the enabled items etc, will become
  877.   normal (not "ghosted") and the user can now select them.
  878.   
  879.   Synopsis:    OnMenu( my_window, menu_number );
  880.  
  881.   my_window:   (struct Window *) Pointer to the window which
  882.                the menu strip is connected to.
  883.   
  884.   menu_number: (USHORT) This menu number specifies what should
  885.                be enabled. Use the macros SHIFTMENU, SHIFTITEM
  886.                and SHIFTSUB to calculate the correct menu
  887.                number. If you just specify a menu, all items to
  888.                that menu will be enabled. If you specify a menu
  889.                and an item, that item will be enabled, so all
  890.                subitem connected to it if there are any.
  891.  
  892.  
  893.  
  894. OpenScreen()
  895.  
  896.   This function will open a Custom Screen with your
  897.   requirements.
  898.  
  899.   Synopsis:      my_screen = OpenScreen( my_new_screen );
  900.   
  901.   my_screen:     (struct Screen *) Pointer to a Screen
  902.                  structure. It will point to your newly opened
  903.                  screen or be equal to NULL if the screen could
  904.                  not be opened.
  905.  
  906.   my_new_screen: (struct NewScreen *) Pointer to a NewScreen
  907.                  structure which contains your preferences.
  908.  
  909.  
  910.  
  911. OpenWindow()
  912.  
  913.   This function will open a window with the characteristics
  914.   defined in the NewWindow structure. It returns a pointer
  915.   to a Window structure.
  916.   
  917.   If you are going to use the Workbench screen, and it has
  918.   been closed, it will automatically reopen. If you on the
  919.   other hand is going to connect the window to a Custom screen,
  920.   you need to open it yourself before calling the OpenWindow()
  921.   function.
  922.   
  923.   Synopsis:      my_window = OpenWindow( my_new_window );
  924.  
  925.   my_window:     (struct Window *) Pointer to a Window structure
  926.                  or NULL if the window could not be opened.
  927.  
  928.   my_new_window: (struct NewWindow *) Pointer to a NewWindow
  929.                  structure which has been initialized with
  930.                  your requirements.
  931.  
  932.  
  933.  
  934. OpenWorkBench()
  935.  
  936.   This function will try to open the Workbench Screen if there
  937.   exist enough memory.
  938.   
  939.   Synopsis:      result = OpenWorkBench();
  940.   
  941.   result:        (long) A boolean value which tell us if the
  942.                  Workbench Screen has been (or already was)
  943.                  opened (TRUE), or not (FALSE).
  944.  
  945.  
  946.  
  947. PrintIText()
  948.  
  949.   This function prints text into a RastPort (Screen/Window).
  950.  
  951.   Synopsis:   PrintIText( rast_port, intui_text, x, y );
  952.  
  953.   rast_port:  (struct RastPort *) Pointer to a RastPort.
  954.  
  955.               If the text should be printed in a window, and
  956.               my_window is a pointer to that window, you write:
  957.               my_window->RPort.
  958.           
  959.               If the text should be printed in a Screen, and
  960.               my_screen is a pointer to that screen, you write:
  961.               my_screen->RastPort.
  962.  
  963.   intui_text: (struct IntuiText *) Pointer to a IntuiText
  964.               structure which has been initialized with your
  965.               requirements.
  966.  
  967.   x:          (long) Number of pixels added to the x position
  968.               of the characters.
  969.  
  970.   y:          (long) Number of lines added to the y position
  971.               of the characters.
  972.  
  973.  
  974.  
  975. RefreshGadgets()
  976.  
  977.   This function redraws all the gadgets in the list, starting
  978.   by the specified gadget. If you for example has added or
  979.   deleted a gadget you need to call this function to see the
  980.   changes. On the other hand, if you have changed the imagery
  981.   of a gadget, or the gadget's image has been trashed by
  982.   something, you can also use this function to refresh the
  983.   display.
  984.   
  985.   Synopsis:  RefreshGadgets( gadget, window, requester);
  986.  
  987.   gadget:    (struct Gadget *) Pointer to the gadget where the
  988.              redrawing should start. This gadget, and all the
  989.              following gadgets in the list will be redrawn.
  990.  
  991.   window:    (struct Window *) Pointer to the window which the
  992.              gadgets are connected to.
  993.   
  994.   requester: (struct Requester *) If the gadget is connected to
  995.              a requester, set this pointer to point to that
  996.              requester, else NULL. Important, if this gadget is
  997.              connected to a requester, it must be displayed
  998.              when you execute this command! (See chapter 5
  999.              REQUESTERS for more information about requesters.)
  1000.  
  1001.  
  1002.  
  1003. RemoveGadget()
  1004.  
  1005.   This function removes a gadget from the list:
  1006.   
  1007.   Synopsis: result = RemoveGadget( window, gadget );
  1008.  
  1009.   result:   (long) The position of the removed gadget or -1 if
  1010.             something went wrong.
  1011.  
  1012.   window:   (struct Window *) Pointer to the window that the
  1013.             gadget is connected to.
  1014.  
  1015.   gadget:   (struct Gadget *) Pointer to the gadget which will
  1016.             be removed.  
  1017.  
  1018.  
  1019.   Important, after your program has removed the necessary
  1020.   gadgets, you need to call the function RefreshGadgets() in
  1021.   order to see your changes. You may take away (or add) several
  1022.   gadgets, but when you are finished you must call that
  1023.   function.
  1024.  
  1025.  
  1026.  
  1027. ReplyMsg()
  1028.  
  1029.   This function tells Intuition that you have finished reading
  1030.   the message. Remember, once you have replied you may not
  1031.   examine or change the IntuiMessage structure any more.
  1032.   
  1033.   Synopsis:   ReplyMsg( my_message );
  1034.   
  1035.   my_message: (struct Message *) Pointer to a Message
  1036.               structure, in this case a pointer to an
  1037.               IntuiMessage structure.
  1038.  
  1039.  
  1040.  
  1041. ReportMouse()
  1042.  
  1043.   You can call this function if you want the window to start/
  1044.   stop reporting the mouse position. (See chapter 8 IDCMP for
  1045.   more information about REPORTMOUSE.)
  1046.   
  1047.   Synopsis:  ReportMouse( my_window, boolean );
  1048.  
  1049.   my_window: (struct Window *) Pointer to a Window structure
  1050.              which has previously been initialized by an
  1051.              OpenWindow() call.
  1052.  
  1053.   boolean:   (long) Set to TRUE if you want the window to start
  1054.              reporting mouse position, else set to FALSE, and
  1055.              the window will stop reporting.
  1056.  
  1057.  
  1058.  
  1059. Request()
  1060.  
  1061.   This function activates a requester connected to a window.
  1062.   
  1063.   Synopsis:     result = Request( my_requester, my_window );
  1064.  
  1065.   my_requester: (struct Requester *) Pointer to the Requester
  1066.                 structure.
  1067.  
  1068.   my_window:    (struct Window *) Pointer to the Window
  1069.                 structure which the requester should be
  1070.                 connected to.
  1071.  
  1072.   result:       (long) Boolean value returned. If Intuition
  1073.                 could successfully open the requester the
  1074.                 function returns TRUE, else (something went
  1075.                 wrong, not enough memory etc) the function
  1076.                 returns FALSE.
  1077.  
  1078.  
  1079.  
  1080. ScreenToBack()
  1081.  
  1082.   This will move the screen behind all other screens.
  1083.   
  1084.   Synopsis:      ScreenToBack( my_screen );
  1085.  
  1086.   my_screen:     (struct Screen *) Pointer to the screen which
  1087.                  you want to move.
  1088.  
  1089.  
  1090.  
  1091. ScreenToFront()
  1092.  
  1093.   This will move the screen in front of all other screens.
  1094.   
  1095.   Synopsis:      ScreenToFront( my_screen );
  1096.  
  1097.   my_screen:     (struct Screen *) Pointer to the screen which
  1098.                  you want to move.
  1099.  
  1100.  
  1101.  
  1102. SetDMRequest()
  1103.  
  1104.   This function allows the user to activate a Double-menu
  1105.   requester by clicking twice on the mouse menu button.
  1106.  
  1107.   Synopsis:  result = SetDMRequest( window, requester );
  1108.  
  1109.   window:    (struct Window *) Pointer to the Window structure
  1110.              which the requester should be connected to.
  1111.  
  1112.   requester: (struct Requester *) Pointer to the Requester
  1113.              structure.
  1114.  
  1115.   result:    (long) Boolean value returned. If Intuition could
  1116.              successfully open the requester the function
  1117.              returns TRUE, else (something went wrong, not
  1118.              enough memory or a DM requester is already
  1119.              connected to the window, etc) the function returns
  1120.              FALSE.
  1121.  
  1122.  
  1123.  
  1124. SetMenuStrip()
  1125.  
  1126.   This function connects a menu strip to a window. Remember
  1127.   that the window must have been opened before you may connect
  1128.   a menu strip to that window.
  1129.  
  1130.   Synopsis:   SetMenuStrip( my_window, my_menu );
  1131.  
  1132.   my_window:  (struct Window *) Pointer to the window which the
  1133.               menu strip should be connected to.
  1134.  
  1135.   my_menu:    (struct Menu *) Pointer to the first Menu
  1136.               structure in the menu strip.
  1137.  
  1138.  
  1139.  
  1140. SetPointer()
  1141.  
  1142.   This function allows you to change the window's pointer.
  1143.   
  1144.   Synopsis:  SetPointer( my_window, data, height, width, x, y );
  1145.  
  1146.   my_window: (struct Window *) Pointer to a Window structure
  1147.              which has previously been initialized by an
  1148.              OpenWindow() call.
  1149.  
  1150.   data:      (short *) Pointer to the Sprite data.
  1151.  
  1152.   width:     (long) The width of the pointer. Less or equal
  1153.              to 16.
  1154.  
  1155.   height:    (long) The height of the pointer. Can be any
  1156.              height.
  1157.  
  1158.   x:        (long) The pointer's "Hot Spot" x position.
  1159.  
  1160.   y:        (long) The pointer's "Hot Spot" y position.
  1161.  
  1162.  
  1163.  
  1164. SetPrefs()
  1165.  
  1166.   This function saves a modified preferences structure. Do NOT
  1167.   change the preferences unless the user really WANTS to!
  1168.  
  1169.   Synopsis: SetPrefs( pref, size, doit );
  1170.  
  1171.   pref:     (struct Preferences *) Pointer to your modified
  1172.             Preferences structure.
  1173.  
  1174.   size:     (long) The number of bytes you want to change.
  1175.  
  1176.   doit:     (long) Boolean value which if FALSE, changes the
  1177.             preferences, but will not send a NEWPREFS message.
  1178.             If doit is equal to TRUE, the settings will be
  1179.             changed, and a NEWPREFS message will be sent.
  1180.             As long as the user is changing the values, doit
  1181.             should be FALSE, but when the user has finished,
  1182.             set it to TRUE, and all programs will get a NEWPREFS
  1183.             message.
  1184.  
  1185.  
  1186.  
  1187. SetWindowTitles()
  1188.  
  1189.   This function allows you to change the window title after the
  1190.   window has been opened.
  1191.   
  1192.   Synopsis:  SetWindowTitles( my_window, window_t, screen_t );
  1193.   
  1194.   my_window: (struct Window *) Pointer to a Window structure
  1195.              which has previously been initialized by an
  1196.              OpenWindow() call.
  1197.  
  1198.   window_t:  (char *) Pointer to a NULL-terminated string which
  1199.              will become the window's title, or
  1200.                 0 : clear title bar, or
  1201.                -1 : keep the old title.
  1202.  
  1203.   screen_t:  (char *) Pointer to a NULL-terminated string which
  1204.              will become the window's screen title, or
  1205.                 0 : clear title bar, or
  1206.                -1 : keep the old title.
  1207.  
  1208.  
  1209.  
  1210. ShowTitle()
  1211.  
  1212.   This function will make the screen's Title appear above or
  1213.   behind any Backdrop Windows (See chapter 2 WINDOWS for more
  1214.   information about Backdrop Windows). (The screen's title
  1215.   appear always behind normal windows.)
  1216.  
  1217.   Synopsis:      ShowTitle( my_screen, show_it );
  1218.  
  1219.   my_screen:     (struct Screen *) Pointer to the screen.
  1220.  
  1221.   show_it:       (long) A boolean value which can be:
  1222.                  TRUE:  The title will be in front of any
  1223.                         Backdrop Windows, but behind any
  1224.                         other windows.
  1225.                  FALSE: The Title will be behind any windows
  1226.  
  1227.  
  1228.  
  1229. SizeWindow()
  1230.  
  1231.   This function will change the size of the window as desired.
  1232.   It has the same effect as if the user would have resized the
  1233.   window by using the Size Gadget.
  1234.  
  1235.   Synopsis:  SizeWindow( my_window, delta_x, delta_y );
  1236.  
  1237.   my_window: (struct Window *) Pointer to a Window structure
  1238.              which has previously been initialized by an
  1239.              OpenWindow() call.
  1240.  
  1241.   delta_x:   (long) Number of pixels the horizontally size of
  1242.              the window will change.
  1243.  
  1244.   delta_y:   (long) Number of pixels the vertically size of the
  1245.              window will change.
  1246.  
  1247.  
  1248.  
  1249. SortGList()
  1250.  
  1251.   This function will reorganize the VSprite list so that the
  1252.   further down on the display the sprites are positioned the
  1253.   later they will appear in the list.
  1254.  
  1255.   Synopsis: SortGList( rp );
  1256.  
  1257.   rp:       (struct RastPort *) Pointer to the RastPort.
  1258.  
  1259.  
  1260.  
  1261. WBenchToBack()
  1262.  
  1263.   This will move the Workbench Screen behind all other screens.
  1264.   
  1265.   Synopsis:      result = WBenchToBack();
  1266.  
  1267.   result:        (long) A boolean value which is TRUE if the
  1268.                  Workbench screen was open, or FALSE it it was
  1269.                  not.
  1270.  
  1271.  
  1272.  
  1273. WBenchToFront()
  1274.  
  1275.   This will move the Workbench Screen in front of all other
  1276.   screens.
  1277.  
  1278.   Synopsis:      result = WBenchToFront();
  1279.  
  1280.   result:        (long) A boolean value which is TRUE if the
  1281.                  Workbench screen was open, or FALSE it it was
  1282.                  not.
  1283.  
  1284.  
  1285.  
  1286. WindowLimits()
  1287.  
  1288.   This function will change the maximum/minimum size limits of
  1289.   the window. Any values which are set to 0 will remain
  1290.   unchanged.
  1291.  
  1292.   Synopsis:  WindowLimits( my_window, min_w, min_h, max_w, max_h );
  1293.  
  1294.   my_window: (struct Window *) Pointer to a Window structure
  1295.              which has previously been initialized by an
  1296.              OpenWindow() call.
  1297.  
  1298.   min_w:     (long) Minimum width of the window.
  1299.  
  1300.   min_h:     (long) Minimum height of the window.
  1301.  
  1302.   max_w:     (long) Maximum width of the window.
  1303.  
  1304.   max_h:     (long) Maximum height of the window.
  1305.  
  1306.  
  1307.  
  1308. WindowToFront()
  1309.  
  1310.   This function will put the window in front of all other
  1311.   windows.
  1312.  
  1313.   Synopsis:  WindowToFront( my_window );
  1314.  
  1315.   my_window: (struct Window *) Pointer to a Window structure
  1316.              which has previously been initialized by an
  1317.              OpenWindow() call.
  1318.  
  1319.  
  1320.  
  1321. WindowToBack()
  1322.  
  1323.   This function will push the window behind all other windows.
  1324.  
  1325.   Synopsis:  WindowToBack( my_window );
  1326.  
  1327.   my_window: (struct Window *) Pointer to a Window structure
  1328.              which has previously been initialized by an
  1329.              OpenWindow() call.
  1330.  
  1331.  
  1332.  
  1333. B.3  GRAPHICS LIBRARY
  1334.  
  1335. The Graphics Library must have been opened before you may call
  1336. these functions. For example:
  1337.  
  1338. struct GfxBase *GfxBase;
  1339.  
  1340. main()
  1341. {
  1342.   /* Open the Graphics Library: */
  1343.   GfxBase = (struct GfxBase *)
  1344.     OpenLibrary( "graphics.library", 0 );
  1345.   
  1346.   if( GfxBase == NULL )
  1347.     exit(); /* Could NOT open the Graphics Library! */
  1348.  
  1349.  
  1350.   ... ...
  1351.  
  1352.  
  1353.   /* Close the Graphics Library: */
  1354.   CloseLibrary( GfxBase );
  1355. }
  1356.  
  1357.  
  1358. AllocRaster()
  1359.  
  1360.   This function reserves display memory (one BitPlane).
  1361.  
  1362.   Synopsis: pointer = AllocRaster( width, height );
  1363.  
  1364.   pointer   (PLANEPTR) Pointer to the allocated memory or NULL
  1365.             if enough memory could not be reserved.
  1366.  
  1367.   width:    (long) The width of the BitMap.
  1368.  
  1369.   height:   (long) The height of the BitMap.
  1370.  
  1371.  
  1372.  
  1373. AreaDraw()
  1374.  
  1375.   This function will add a new vertex to the vector list. 
  1376.  
  1377.   Synopsis:  AreaDraw( rast_port, x, y );
  1378.  
  1379.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1380.              should be affected.
  1381.  
  1382.   x:         (long) New X position.
  1383.  
  1384.   y:         (long) New Y position.
  1385.  
  1386.  
  1387.  
  1388. AreaEnd()
  1389.  
  1390.   This function will close, draw and fill the polygon.
  1391.  
  1392.   Synopsis:  AreaEnd( rast_port );
  1393.  
  1394.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1395.              should be affected.
  1396.  
  1397.  
  1398.  
  1399. AreaMove()
  1400.  
  1401.   This function will start a new polygon.
  1402.  
  1403.   Synopsis:  AreaMove( rast_port, x, y );
  1404.  
  1405.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1406.              should be affected.
  1407.  
  1408.   x:         (long) Start X position.
  1409.  
  1410.   y:         (long) Start Y position.
  1411.  
  1412.  
  1413.  
  1414. BltBitMap()
  1415.  
  1416.   This function copies parts of BitMaps directly without
  1417.   worrying about overlapping layers.
  1418.  
  1419.   Synopsis: BltBitMap( sb, sx, sy, db, dx, dy, w, h, fl, m, t );
  1420.  
  1421.   sb:       (struct BitMap *) Pointer to the "source" BitMap.
  1422.  
  1423.   sx:       (long) X offset, source.
  1424.  
  1425.   sy:       (long) Y offset, source.
  1426.  
  1427.   db:       (struct BitMap *) Pointer to the "destination"
  1428.             BitMap.
  1429.  
  1430.   dx:       (long) X offset, destination.
  1431.  
  1432.   dy:       (long) Y offset, destination.
  1433.  
  1434.   w:        (long) The width of the memory area that should be
  1435.             copied.
  1436.  
  1437.   h:        (long) The height of the memory area that should be
  1438.             copied.
  1439.  
  1440.   fl:       (long) The four leftmost bits tells the blitter
  1441.             what kind of logically operations should be done.
  1442.  
  1443.   m:        (long) You can here define a BitMap mask, and tell
  1444.             the blitter which BitPlanes should be used, and
  1445.             which should not. The first bit represents the
  1446.             first BitPlane, the second bit the second BitPlane
  1447.             and so on. If the bit is on (1) the corresponding
  1448.             BitPlane will be used, else (0) the BitPlane will
  1449.             not be used. To turn off BitPlane zero and two, set
  1450.             the mask value to 0xFA (11111010). To use all
  1451.             BitPlanes set the mask value to 0xFF (11111111).
  1452.  
  1453.   t:        (char *) If the copy overlaps and this pointer
  1454.             points to some chip-memory, the memory will be used
  1455.             to store the temporary area in. However, normally
  1456.             you do not need to bother about this value.
  1457.  
  1458.  
  1459.  
  1460. BltClear()
  1461.  
  1462.   This function clears large rectangular memory areas. This
  1463.   function work together with the blitter and is therefore very
  1464.   fast.
  1465.  
  1466.   Synopsis: BltClear( pointer, bytes, flags );
  1467.  
  1468.   pointer   (char *) Pointer to the memory.
  1469.  
  1470.   bytes:    (long) The lower 16 bits tells the blitter how many
  1471.             bytes per row, and the upper 16 bits how many rows.
  1472.             This value is automatically calculated for you with
  1473.             help of the macro RASSIZE(). Just give RASSIZE()
  1474.             the correct width and height and it will return the
  1475.             correct value. [RASSIZE() is defined in file
  1476.             "gfx.h".]
  1477.  
  1478.   flags:    (long) Set bit 0 to force the function to wait
  1479.             until the Blitter has finished with your request.
  1480.  
  1481.  
  1482.  
  1483. BNDROFF()
  1484.  
  1485.   This macro (declared in file "gfxmacro.h") will turn off the
  1486.   outline mode.
  1487.  
  1488.   Synopsis:  BNDROFF( rast_port );
  1489.  
  1490.   rast_port: Pointer to the RastPort which outlinefunction
  1491.              should be turned off.
  1492.  
  1493.  
  1494.  
  1495. ClipBlit()
  1496.  
  1497.   This function copies parts of BitMaps with help of Rastports
  1498.   and will therefore care about overlapping layers, and should
  1499.   be used if you have windows on your display.
  1500.  
  1501.   Synopsis: ClipBlit( srp, sx, sy, drp, dx, dy, w, h, flag );
  1502.  
  1503.   srp:      (struct RastPort *) Pointer to the "source"
  1504.             RastPort.
  1505.  
  1506.   sx:       (long) X offset, source.
  1507.  
  1508.   sy:       (long) Y offset, source.
  1509.  
  1510.   drp:      (struct RastPort *) Pointer to the "destination"
  1511.             RastPort.
  1512.  
  1513.   dx:       (long) X offset, destination.
  1514.  
  1515.   dy:       (long) Y offset, destination.
  1516.  
  1517.   w:        (long) The width of the memory area that should be
  1518.             copied.
  1519.  
  1520.   h:        (long) The height of the memory area that should be
  1521.             copied.
  1522.  
  1523.   flag:     (long) This value tells the blitter what kind of
  1524.             logically operations should be done. See below for
  1525.             more information.
  1526.  
  1527.  
  1528.  
  1529. Draw()
  1530.  
  1531.   This function draws single lines from the current position
  1532.   to the new specified position.
  1533.  
  1534.   Synopsis:  Draw( rast_port, x, y );
  1535.  
  1536.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1537.              should be affected.
  1538.  
  1539.   x:         (long) The new X position. 
  1540.  
  1541.   y:         (long) The new Y position.
  1542.  
  1543.  
  1544.  
  1545. Flood()
  1546.  
  1547.   This function will flood fill complicated objects.
  1548.  
  1549.   Synopsis:  Flood( rast_port, mode, x, y ); 
  1550.  
  1551.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1552.              should be affected.
  1553.  
  1554.   mode:      (long) Which mode should be used. If you want to
  1555.              use the Colour mode set the mode variable to 1, to
  1556.              get the Outline mode set the mode variable to 0.
  1557.  
  1558.   x:         (long) X position where the flood fill should
  1559.              start.
  1560.  
  1561.   y:         (long) Y position where the flood fill should
  1562.              start.
  1563.  
  1564.  
  1565.  
  1566. FreeColorMap()
  1567.  
  1568.   This function deallocates the memory that was allocated by
  1569.   the GetColorMap() function. Remember to deallocate all memory
  1570.   that you allocate. For every GetColorMap() function there
  1571.   should be one FreeColorMap() function.
  1572.  
  1573.   FreeColorMap( colormap );
  1574.  
  1575.   colormap: (struct ColorMap *) Pointer to a ColorMap structure
  1576.             that GetColorMap() returned and you now want to
  1577.             deallocate.
  1578.  
  1579.  
  1580.  
  1581. FreeCprList()
  1582.  
  1583.   This function will return all memory that was automatically
  1584.   allocated by the MrgCop() function.
  1585.  
  1586.   Synopsis: FreeCprList( cprlist );
  1587.  
  1588.   cprlist:  (struct cprlist *) Pointer to the View's cprlist
  1589.             (LOFCprList) structure. If the View was interlaced
  1590.             you must also call the FreeCprList function with a
  1591.             pointer to the SHFCprList.
  1592.  
  1593.  
  1594.  
  1595. FreeRaster()
  1596.  
  1597.   This function will deallocate display memory (BitPlane).
  1598.   Remember to deallocate all BitPlanes!
  1599.  
  1600.   Synopsis: FreeRaster( bitplane, width, height );
  1601.  
  1602.   bitplane: (PLANEPTR) Pointer to a Bitplane.
  1603.  
  1604.   width:    (long) The Bitplane's width.
  1605.  
  1606.   height:   (long) The Bitplane's height.
  1607.  
  1608.  
  1609.  
  1610. FreeVPortCopLists()
  1611.  
  1612.   This function will return all memory that was automatically
  1613.   allocated by the MakeVPort() function. Remember to call
  1614.   FreeVPortCopLists() for every ViewPort you have created!
  1615.  
  1616.   Synopsis: FreeVPortCopLists( viewport );
  1617.  
  1618.   view:     (struct ViewPort *) Pointer to the ViewPort.
  1619.  
  1620.  
  1621.  
  1622. GetColorMap()
  1623.  
  1624.   This function allocates and initializes a ColorMap structure.
  1625.  
  1626.   Synopsis: colormap = GetColorMap( colours );
  1627.  
  1628.   colormap: (struct ColorMap *) GetColorMap returns a pointer
  1629.             to the ColorMap structure it has allocated and
  1630.             initialized, or NULL if not enough memory.
  1631.  
  1632.   colours:  (long) A value specifying how many colours you
  1633.             want that the ColorMap structure should store.
  1634.             (1, 2, 4, 8, 16, 32)
  1635.  
  1636.  
  1637.  
  1638. InitBitMap()
  1639.  
  1640.   This function initializes a BitMap structure.
  1641.  
  1642.   Synopsis: InitBitMap( bitmap, depth, width, height );
  1643.  
  1644.   bitmap: (struct BitMap *) Pointer to the BitMap.
  1645.  
  1646.   depth:  (long) How many BitPlanes used.
  1647.  
  1648.   width:  (long) The width of the raster.
  1649.  
  1650.   height: (long) The height of the raster.
  1651.  
  1652.  
  1653.  
  1654. InitRastPort()
  1655.  
  1656.   This function initializes a RastPort.
  1657.  
  1658.   Synopsis:  InitRastPort( rast_port );
  1659.  
  1660.   rast_port: (RastPort *) Pointer to the RastPort that should
  1661.              be Initialized.
  1662.  
  1663.  
  1664.  
  1665. InitView()
  1666.  
  1667.   This function will initialize a View structure.
  1668.  
  1669.   Synopsis: InitView( view );
  1670.   
  1671.   view:     (struct View *) Pointer to the View that should be
  1672.             initialized.
  1673.  
  1674.  
  1675.  
  1676. InitVPort()
  1677.  
  1678.   This function will initialize a ViewPort structure.
  1679.  
  1680.   Synopsis:  InitVPort( view_port );
  1681.   
  1682.   view_port: (struct ViewPort *) Pointer to the ViewPort that
  1683.              should be initialized.
  1684.  
  1685.  
  1686.  
  1687. MakeVPort()
  1688.  
  1689.   This function prepares the Amiga's hardware (especially the
  1690.   Copper) to display a ViewPort. NOTE! You have to prepare
  1691.   EVERY ViewPort you are going to use!
  1692.  
  1693.   Synopsis: MakeVPort( view, viewport ); 
  1694.  
  1695.   view:     (struct View *) Pointer to the ViewPort's View.
  1696.  
  1697.   viewport: (struct ViewPort *) Pointer to the ViewPort.
  1698.  
  1699.  
  1700.  
  1701. Move()
  1702.  
  1703.   This function moves the cursor.
  1704.  
  1705.   Synopsis:  Move( rast_port, x, y );
  1706.  
  1707.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1708.              should be affected.
  1709.  
  1710.   x:         (long) The new X position. 
  1711.  
  1712.   y:         (long) The new Y position.
  1713.  
  1714.  
  1715.  
  1716. MrgCop()
  1717.  
  1718.   This function puts together all displayinstructions and
  1719.   prepares the view to be showed.
  1720.  
  1721.   Synopsis: MrgCop( view );
  1722.  
  1723.   view:     (struct View *) Pointer to the View.
  1724.  
  1725.  
  1726.  
  1727. LoadView()
  1728.  
  1729.   This function will start showing a View. Remember that when
  1730.   you close your View you must switch back to the old view.
  1731.   (See examples for more details.)
  1732.  
  1733.   Synopsis: LoadView( view );
  1734.  
  1735.   view:     (struct View *) Pointer to the View.
  1736.  
  1737.  
  1738.  
  1739. PolyDraw()
  1740.  
  1741.   This function will draw multiple lines.
  1742.  
  1743.   Synopsis:    PolyDraw( rast_port, number, coordinates );
  1744.  
  1745.   rast_port:   (struct RastPort *) Pointer to the RastPort that
  1746.                should be affected.
  1747.  
  1748.   number:      (long) The number of coordinates (x,y) defined
  1749.                in the array.
  1750.  
  1751.   coordinates: (short *) Pointer to an array of coordinates.
  1752.  
  1753.  
  1754.  
  1755. ReadPixel()
  1756.  
  1757.   This function reads the colour value of a pixel.
  1758.  
  1759.   Synopsis:  colour = ReadPixel( rast_port, x, y );
  1760.  
  1761.   colour:    (long) ReadPixel returns the colour value of the
  1762.              specified pixel (colour 0 - 255 ) or -1 if the
  1763.              coordinates were outside the Raster.
  1764.  
  1765.   rast_port: (struct RastPort *) Pointer to the RastPort which
  1766.              contain the pixel you want to examine.
  1767.  
  1768.   x:         (long) X position of the pixel. 
  1769.  
  1770.   y:         (long) Y position of the pixel.
  1771.  
  1772.  
  1773.  
  1774. RectFill()
  1775.  
  1776.   This function will draw filled rectangles.
  1777.  
  1778.   Synopsis:  RectFill( rast_port, minx, miny, maxx, maxy );
  1779.  
  1780.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1781.              should be affected.
  1782.  
  1783.   minx:      (long) Left position of the rectangle.
  1784.  
  1785.   miny:      (long) Top          - " -
  1786.  
  1787.   maxx:      (long) Right        - " -
  1788.  
  1789.   maxy:      (long) Bottom       - " -
  1790.  
  1791.  
  1792.  
  1793. SetAfPt()
  1794.  
  1795.   This function will set the area pattern:
  1796.  
  1797.   Synopsis:     SetAfPt( rast_port, area_pattern, pow2 );
  1798.  
  1799.   rast_port:    (struct RastPort *) Pointer to the RastPort
  1800.                 that should be affected.
  1801.  
  1802.   area_pattern: (UWORD) Pointer to an array of UWORDS that
  1803.                 generate the pattern. Each bit in the array
  1804.                 represents one dot.
  1805.  
  1806.   pow2:         (BYTE) The pattern must be two to the power of
  1807.                 pow2 lines tall. If the pattern is one line tall
  1808.                  pow2 should be set to 0, if the pattern is two
  1809.                 lines tall pow2 should be set to 1, if the
  1810.                 pattern is four lines tall pow2 should be set to
  1811.                 2, and so on. (If you use multicoloured patterns
  1812.                 the pow2 should be negative. A sixteen lines
  1813.                 tall multicoloured pattern should therefore have
  1814.                 the pow2 value set to -4 [2^4 = 16].)
  1815.  
  1816.  
  1817.  
  1818. SetAPen()
  1819.  
  1820.   This function will change the FgPen's colour.
  1821.  
  1822.   Synopsis:   SetAPen( rast_port, new_colour );
  1823.  
  1824.   rast_port:  (struct RastPort *) Pointer to the RastPort that
  1825.               should be affected.
  1826.  
  1827.   new_colour: (long) A new colour value.
  1828.  
  1829.  
  1830.  
  1831. SetBPen()
  1832.  
  1833.   This function will change the BgPen's colour.
  1834.  
  1835.   Synopsis:   SetBPen( rast_port, new_colour );
  1836.  
  1837.   rast_port:  (struct RastPort *) Pointer to the RastPort that
  1838.               should be affected.
  1839.  
  1840.   new_colour: (long) A new colour value.
  1841.  
  1842.  
  1843.  
  1844. SetDrMd()
  1845.  
  1846.   This function will change the drawing mode.
  1847.  
  1848.   Synopsis:  SetDrMd( rast_port, new_mode );
  1849.  
  1850.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1851.              should be affected.
  1852.  
  1853.   new_mode:  (long) The new drawing mode. Set one of the
  1854.              following: JAM1, JAM2, COMPLEMENT, INVERSVID|JAM1
  1855.              or INVERSVID|JAM2.
  1856.  
  1857.              JAM1           The FgPen will be used, the
  1858.                             background unchanged. (One colour
  1859.                             jammed into a Raster.)
  1860.  
  1861.              JAM2           The FgPen will be used as foreground
  1862.                             pen while the background (when you
  1863.                             are writing text for example) will
  1864.                             be filled with the BgPen's colour.
  1865.                             (Two colours are jammed into a
  1866.                             Raster.)
  1867.  
  1868.              COMPLEMENT     Each pixel affected will be drawn
  1869.                             with the binary complement colour.
  1870.                             Where you write 1's the
  1871.                             corresponding bit in the Raster
  1872.                             will be reversed.
  1873.  
  1874.              INVERSVID|JAM1 This mode is only use together with
  1875.                             text. Only the background of the
  1876.                             text will be drawn with the FgPen.
  1877.  
  1878.              INVERSVID|JAM2 This mode is only use together with
  1879.                             text. The background of the text
  1880.                             will be drawn with the FgPen, and
  1881.                             the characters itself with the
  1882.                             BgPen.
  1883.  
  1884.  
  1885.  
  1886. SetDrPt()
  1887.  
  1888.   This function will set the line pattern.
  1889.  
  1890.   Synopsis:     SetDrPt( rast_port, line_pattern );
  1891.  
  1892.   rast_port:    (struct RastPort *) Pointer to the RastPort
  1893.                 that should be affected.
  1894.  
  1895.   line_pattern: (UWORD) The pattern. Each bit represents one
  1896.                 dot. To generate solid lines you set the
  1897.                 pattern value to 0xFFFF [hex] (1111111111111111
  1898.                 [bin]).
  1899.  
  1900.  
  1901.  
  1902. SetOPen()
  1903.  
  1904.   This macro will change the AOlPen's colour. Note! This is not
  1905.   a function. It is actually a macro that is defined in the
  1906.   header file "gfxmacros.h". If you want to use this function
  1907.   you have to remember to include this file.
  1908.  
  1909.   Synopsis:   SetOPen( rast_port, new_colour );
  1910.  
  1911.   rast_port:  (struct RastPort *) Pointer to the RastPort that
  1912.               should be affected.
  1913.  
  1914.   new_colour: (long) A new colour value.
  1915.  
  1916.  
  1917.  
  1918. SetRast()
  1919.  
  1920.   This function sets a whole Raster to a specific colour.
  1921.  
  1922.   Synopsis:  SetRast( rast_port, colour );
  1923.  
  1924.   rast_port: (struct RastPort *) Pointer to the RastPort that
  1925.              should be affected.
  1926.  
  1927.   colour:    (long) The colour reg. you want to fill the whole
  1928.              raster with.
  1929.  
  1930.  
  1931.  
  1932. SetRGB4()
  1933.  
  1934.   This function allows you to change your screen's colours.
  1935.   Each colour may be picked out of a 4096 colour palette. (16
  1936.   levels of red, 16 levels of green and 16 levels of blue;
  1937.   16*16*16 = 4096.)
  1938.  
  1939.   IMPORTANT! Before you may use this function you must have
  1940.   opened the Graphics Library. (All other functions are in the
  1941.   Intuition Library.) (See chapter 0 AMIGA for more
  1942.   information.)
  1943.  
  1944.   Synopsis:   SetRGB4( viewport, register, red, green, blue );
  1945.            
  1946.   viewport:   (struct ViewPort *) Pointer to a ViewPort which
  1947.               colour registers we are going to change. We can
  1948.               find the screen's ViewPort in the Screen
  1949.               structure. (If my_screen is a pointer to a Screen
  1950.               structure, this will get us a pointer to that
  1951.               screen's ViewPort: &my_screen->ViewPort)
  1952.  
  1953.   register:   (long) The colour register you want to change.
  1954.               The screen's Depth decides how many colour
  1955.               registers the screen have:
  1956.  
  1957.               Depth  Colour Registers
  1958.               -----------------------
  1959.               1      0 - 1
  1960.               2      0 - 3
  1961.               3      0 - 7
  1962.               4      0 - 15
  1963.               5      0 - 31
  1964.               6      0 - 63
  1965.  
  1966.   red:        Amount of red. (0 - 15)
  1967.  
  1968.   green:      Amount of green. (0 - 15 )
  1969.  
  1970.   blue:       Amount of blue. (0 - 15 )
  1971.  
  1972.   Eg: SetRGB4( &my_screen->ViewPort, 2, 15, 15, 0 ); will
  1973.   change colour register 2 to be light yellow. (Red and green
  1974.   together will be yellow.)
  1975.  
  1976.  
  1977.  
  1978. ScrollRaster()
  1979.  
  1980.   This function will scroll a rectangular area of a raster.
  1981.  
  1982.   Synopsis:  ScrollRaster( rp, dx, dy, minx, miny, maxx, maxy );
  1983.  
  1984.   rp:        (struct RastPort *) Pointer to the RastPort that
  1985.              should be affected.
  1986.  
  1987.  
  1988.   dx:        (long) Delta X movement. (A positive number moves
  1989.              the area to the right, a negative number to the
  1990.              left.)
  1991.  
  1992.   dy:        (long) Delta Y movement. (A positive number moves
  1993.              the area down, a negative number up.)
  1994.  
  1995.   minx:      (long) Left edge of the rectangle.
  1996.  
  1997.   miny:      (long) Top edge of the rectangle.
  1998.  
  1999.   maxx:      (long) Right edge of the rectangle.
  2000.  
  2001.   maxy:      (long) Bottom edge of the rectangle.
  2002.  
  2003.  
  2004.  
  2005. Text()
  2006.  
  2007.   This function prints text into a Raster.
  2008.  
  2009.   Synopsis:  Text( rast_port, string, nr_of_chr );
  2010.  
  2011.   rast_port: (struct RastPort *) Pointer to the RastPort that
  2012.              should be affected.
  2013.  
  2014.   string:    (char *) Pointer to a text string that will be
  2015.              printed.
  2016.  
  2017.   nr_of_chr: (long) The number of characters that should be
  2018.              printed.
  2019.  
  2020.  
  2021.  
  2022. WritePixel()
  2023.  
  2024.   This function will draw a single pixel.
  2025.  
  2026.   Synopsis:  WritePixel( rast_port, x, y );
  2027.  
  2028.   rast_port: (struct RastPort *) Pointer to the RastPort that
  2029.              should be affected.
  2030.  
  2031.   x:         (long) X position of the pixel. 
  2032.  
  2033.   y:         (long) Y position of the pixel.
  2034.  
  2035.  
  2036.  
  2037. B.4  EXEC LIBRARY
  2038.  
  2039. AllocMem()
  2040.  
  2041.   This function allocates memory. You specifies what type and
  2042.   how much you want, and it returns a pointer to the allocated
  2043.   memory, or NULL if there did not exist enough memory.
  2044.  
  2045.   Synopsis: memory = AllocMem( size, type );
  2046.  
  2047.   memory:   (void *) Pointer to the new allocated memory, or
  2048.             NULL if no memory could be allocated. Remember!
  2049.             Never use memory which you have not successfully
  2050.             allocated.
  2051.  
  2052.   size:     (long) The size (in bytes) of the memory you want.
  2053.             (AllocMem() always allocates memory in multiples of
  2054.             eight bytes. So if you only ask for 9 bytes, Exec
  2055.             would actually give you 16 Bytes (2*8).)
  2056.  
  2057.   type:     (long) You need to choose one of the three
  2058.             following types of memory (see chapter 0
  2059.             INTRODUCTION for more information about Chip and
  2060.             Fast memory):
  2061.  
  2062.             MEMF_CHIP   Chip memory. This memory can be
  2063.                         accessed by both the main processor, as
  2064.                         well as the Chips. Graphics/Sound data
  2065.                         MUST therefore be placed in Chip memory.
  2066.                         If it does not matter what type of 
  2067.                         memory you get (Fast or Chip), you
  2068.                         should try to allocate Fast memory
  2069.                         before you allocate Chip memory. (Chip
  2070.                         memory is more valuable than Fast
  2071.                         memory.)
  2072.  
  2073.             MEMF_FAST   Fast memory. This memory can only be
  2074.                         accessed by the main processor.
  2075.                         (Graphics and Sound data can NOT be
  2076.                         stored in Fast memory, use Chip memory.)
  2077.                         This memory is normally a little bit
  2078.                         faster than Chip memory, since only the
  2079.                         main processor is working with it, and
  2080.                         it is not disturbed by the Chips.
  2081.  
  2082.             MEMF_PUBLIC If it does not matter what type of
  2083.                         memory you get (you do not intend to
  2084.                         use the memory for Graphics/Sound data),
  2085.                         you should use Fast memory. However,
  2086.                         all Amigas do not have Fast memory,
  2087.                         since you need to by a memory expansion
  2088.                         in order to get it. If want to tell
  2089.                         Exec that you would like to use Fast
  2090.                         memory if there is any, else use Chip
  2091.                         memory, you should ask for MEMF_PUBLIC.
  2092.  
  2093.             If you want the allocated memory to be cleared
  2094.             (initialized to zeros), you should set the flag
  2095.             MEMF_CLEAR.
  2096.  
  2097.  
  2098.  
  2099. FreeMem()
  2100.  
  2101.   This function deallocated previously allocated memory.
  2102.   Remember to deallocate all memory you have taken, and never
  2103.   deallocate memory which you have not taken.
  2104.  
  2105.   Synopsis: FreeMem( memory, size );
  2106.  
  2107.   memory    (void *) Pointer to some memory which has
  2108.             previously been allocated. Remember! never use
  2109.             memory which has been deallocated.
  2110.  
  2111.   size      (long) The size (in bytes) of the memory you want
  2112.             to deallocate.
  2113.  
  2114.  
  2115.  
  2116. B.5  AMIGA DOS LIBRARY
  2117.  
  2118. Close()
  2119.  
  2120.   This function closes an already opened file. Remember to
  2121.   close ALL files you have opened!
  2122.  
  2123.   Synopsis:    Close( file_handle );
  2124.  
  2125.   file_handle: (BPTR) Actually a pointer to a FileHandle
  2126.                structure which has been initialized by a
  2127.                previous Open() call.
  2128.  
  2129.  
  2130.  
  2131. CreateDir()
  2132.  
  2133.   This function creates a new directory, AND "locks" is
  2134.   automatically. (Remember to unlock the directory later on.)
  2135.  
  2136.   Synopsis: lock = CreateDir( name );
  2137.  
  2138.   lock:     (BPTR) Actually a pointer to a FileLock structure.
  2139.             If lock is equal to NULL, AmigaDOS have not been
  2140.             able to create the new directory.
  2141.  
  2142.   name:     (char *) Pointer to a string containing the name
  2143.             of the new directory.
  2144.  
  2145.  
  2146.  
  2147. CurrentDir()
  2148.  
  2149.   This function makes a specified directory "current
  2150.   directory". You need to lock the new directory (new_lock)
  2151.   before you can make it the current directory. The function
  2152.   returns the old current directories lock so you can unlock
  2153.   it if necessary.
  2154.   
  2155.   Synopsis: old_lock = CurrentDir( new_lock );
  2156.   
  2157.   old_lock: (BPTR) Actually a pointer to a FileLock structure.
  2158.             It is the old current directory lock.
  2159.   
  2160.   new_lock: (BPTR) Actually a pointer to a FileLock structure.
  2161.             The new current directory lock.
  2162.  
  2163.  
  2164.  
  2165. DeleteFile()
  2166.  
  2167.   This function deletes a file or directory. Remember that
  2168.   a directory must be empty before it can be deleted.
  2169.  
  2170.   Synopsis: ok = DeleteFile( name );
  2171.  
  2172.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  2173.             could delete the file/directory, else FALSE which
  2174.             means something went wrong. (Eg. disk write-
  2175.             protected, directory not empty etc.)
  2176.  
  2177.   name:     (char *) Pointer to a string containing the name
  2178.             of the file/directory you want to delete. 
  2179.  
  2180.  
  2181.  
  2182. Info()
  2183.  
  2184.   This function returns information about a specified disk. You
  2185.   specify which disk by either lock that disk, or a file/
  2186.   directory on that disk.
  2187.  
  2188.   Synopsis:  ok = Info( lock, info_data );
  2189.   
  2190.   ok:        (long) Actually a Boolean. It is TRUE if AmigaDOS
  2191.              could get information about the disk, else FALSE
  2192.              which means something went wrong.
  2193.  
  2194.   lock:      (BPTR) Actually a pointer to a FileLock structure.
  2195.  
  2196.   info_data: (struct InfoData *) Pointer to an InfoData
  2197.              structure which will be initialized by the Info()
  2198.              function. The problem with this structure is that
  2199.              it must be on a four byte boundary, so you need
  2200.              to use the function AllocMem() to get the right
  2201.              type of memory for the structure. (See Example.)
  2202.  
  2203.  
  2204.  
  2205. IoErr()
  2206.  
  2207.   This function can be used to get more information about an
  2208.   error message. Whenever you have used an AmigaDOS function
  2209.   which did not work properly (you have received an error
  2210.   message), you call this function and it will return an
  2211.   explanation.
  2212.   
  2213.   Synopsis: error = IoErr();
  2214.   
  2215.   error:    (long) This field contains a flag returned by
  2216.             IoErr() which can be: (I do not think I need
  2217.             to explain what they mean.)
  2218.  
  2219.             ERROR_NO_FREE_STORE
  2220.             ERROR_TASK_TABLE_FULL
  2221.             ERROR_LINE_TOO_LONG
  2222.             ERROR_FILE_NOT_OBJECT
  2223.             ERROR_INVALID_RESIDENT_LIBRARY
  2224.             ERROR_NO_DEFAULT_DIR
  2225.             ERROR_OBJECT_IN_USE
  2226.             ERROR_OBJECT_EXISTS
  2227.             ERROR_DIR_NOT_FOUND
  2228.             ERROR_OBJECT_NOT_FOUND
  2229.             ERROR_BAD_STREAM_NAME
  2230.             ERROR_OBJECT_TOO_LARGE
  2231.             ERROR_ACTION_NOT_KNOWN
  2232.             ERROR_INVALID_COMPONENT_NAME
  2233.             ERROR_INVALID_LOCK
  2234.             ERROR_OBJECT_WRONG_TYPE
  2235.             ERROR_DISK_NOT_VALIDATED
  2236.             ERROR_DISK_WRITE_PROTECTED
  2237.             ERROR_RENAME_ACROSS_DEVICES
  2238.             ERROR_DIRECTORY_NOT_EMPTY
  2239.             ERROR_TOO_MANY_LEVELS
  2240.             ERROR_DEVICE_NOT_MOUNTED
  2241.             ERROR_SEEK_ERROR
  2242.             ERROR_COMMENT_TOO_BIG
  2243.             ERROR_DISK_FULL
  2244.             ERROR_DELETE_PROTECTED
  2245.             ERROR_WRITE_PROTECTED
  2246.             ERROR_READ_PROTECTED
  2247.             ERROR_NOT_A_DOS_DISK
  2248.             ERROR_NO_DISK
  2249.             ERROR_NO_MORE_ENTRIES
  2250.  
  2251.  
  2252.  
  2253. Open()
  2254.  
  2255.   This function opens a file. Remember, before you can read/
  2256.   write files you have to open them. 
  2257.  
  2258.   Synopsis:    file_handle = Open( file_name, mode );
  2259.  
  2260.   file_handle: (BPTR) Actually a pointer to a FileHandle
  2261.                structure. If the system could not open the file
  2262.                with our requirements Open() returns NULL.
  2263.  
  2264.   file_name:   (char *) Pointer to a text string which contains
  2265.                the file name including any necessary devices/
  2266.                directories.
  2267.  
  2268.   mode:        (long) When you open a file you need to tell the
  2269.                system what you are going to do with it. This
  2270.                field should therefore contain one of the
  2271.                following flags:
  2272.  
  2273.                MODE_OLDFILE:   Opens an existing file for
  2274.                                reading and writing.
  2275.  
  2276.                MODE_NEWFILE:   Opens a new file for writing.
  2277.                                (If the file already exist it
  2278.                                is deleted.)
  2279.  
  2280.                MODE_READWRITE: Opens an old file with an
  2281.                                exclusive lock. (The file is
  2282.                                automatically locked with an
  2283.                                EXCLUSIVE_LOCK.)
  2284.  
  2285.                MODE_READONLY:  Same as MODE_OLDFILE.
  2286.  
  2287.  
  2288.  
  2289. Read()
  2290.  
  2291.   This function reads a specified number of bytes from a file.
  2292.  
  2293.   Synopsis:    bytes_read = Read( file_handle, buffer, size );
  2294.  
  2295.   bytes_read:  (long) Number of bytes actually read. Even if
  2296.                you tell AmigaDOS that you want to read x
  2297.                number of bytes, it is not certain that you
  2298.                actually can do it. The file is maybe corrupted,
  2299.                not as big as you thought etc.
  2300.  
  2301.   file_handle: (BPTR) Actually a pointer to a FileHandle
  2302.                structure which has been initialized by a
  2303.                previous Open() call.
  2304.  
  2305.   buffer:      (char *) Pointer to the data buffer you want to
  2306.                read the data into.
  2307.  
  2308.   size:        (long) Number of bytes you want to read.
  2309.  
  2310.  
  2311.  
  2312. Rename()
  2313.  
  2314.   This function renames a file or directory. You can even
  2315.   move a file between directories by renaming it. (For example,
  2316.   Rename( "df0:Documents/Sale.doc", "df0:Letters/Sale.doc" );
  2317.   will move the file Sale.doc from the directory "Documents"
  2318.   to directory "Letters". Note! You can not rename a file from
  2319.   one volume to another.)
  2320.   
  2321.   Synopsis: ok = Rename( old_name, new_name );
  2322.   
  2323.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  2324.             could rename the file/directory, else FALSE which
  2325.             means something went wrong. (Eg. disk write
  2326.             -protected.)
  2327.  
  2328.   old_name: (char *) Pointer to a string containing the old
  2329.             file/directory name.
  2330.  
  2331.   new_name: (char *) Pointer to a string containing the new
  2332.             file/directory name.
  2333.  
  2334.  
  2335.  
  2336. Seek()
  2337.  
  2338.   This function moves the "file cursor" inside a file:
  2339.  
  2340.   Synopsis:    old_pos = Seek( file_handle, new_pos, mode );
  2341.  
  2342.   old_pos:     (long) Previous position in the file, or -1 if
  2343.                an error occurred.
  2344.  
  2345.   file_handle: (BPTR) Actually a pointer to a FileHandle
  2346.                structure which has been initialized by a
  2347.                previous Open() call.
  2348.  
  2349.   new_pos:     (long) New position relative to the "mode".
  2350.  
  2351.   mode:        (long) The new_pos can be relative to:
  2352.                  OFFSET_BEGINNING: Beginning of the file.
  2353.                  OFFSET_CURRENT:   Current position.
  2354.                  OFFSET_END:       The end of the file.
  2355.  
  2356.  
  2357.  
  2358. SetComment
  2359.  
  2360.   This function attach a comment to a file or directory.
  2361.  
  2362.   Synopsis: ok = SetComment( name, comment );
  2363.  
  2364.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  2365.             could attach the new comment, else FALSE which
  2366.             means something went wrong. (Eg. disk write-
  2367.             protected.)
  2368.  
  2369.   name:     (char *) Pointer to a string containing the name
  2370.             of the file/directory you want to attach the
  2371.             comment to.
  2372.  
  2373.   comment:  (char *) Pointer to a string containing the
  2374.             comment. (A comment may be up to 80 characters
  2375.             long.)
  2376.  
  2377.  
  2378.  
  2379. SetProtection()
  2380.  
  2381.   This function alters the protection bits of a file.
  2382.   You can set following flags:
  2383.   
  2384.   FIBF_DELETE  : the file/directory can not be deleted.
  2385.   FIBF_EXECUTE : the file can not be executed.
  2386.   FIBF_WRITE   : you can not write to the file.
  2387.   FIBF_READ    : you can not read the file.
  2388.   FIBF_ARCHIVE : Archive bit.
  2389.   FIBF_PURE    : Pure bit.
  2390.   FIBF_SCRIPT  : Script bit.
  2391.  
  2392.   (Note! All of the flags are for the moment not working!)
  2393.   
  2394.   Synopsis: ok = SetProtection( name, mask );
  2395.   
  2396.   ok:       (long) Actually a Boolean. It is TRUE if AmigaDOS
  2397.             could alter the protection bits, else FALSE which
  2398.             means something went wrong. (Eg. disk write-
  2399.             protected.)
  2400.  
  2401.   name:     (char *) Pointer to a string containing the name
  2402.             of the file/directory you want to change the
  2403.             protection bits.
  2404.  
  2405.   mask:     (long) The protection bits. (For example, if you
  2406.             want to make the file/directory not deletable,
  2407.             and that it can not be executed you should set the
  2408.             protection bits: FIBF_DELETE | FIBF_EXECUTE.)
  2409.  
  2410.  
  2411.  
  2412. UnLock()
  2413.  
  2414.   This function unlocks a previously locked file: (Remember to
  2415.   unlock ALL files you have locked!)
  2416.  
  2417.   Synopsis: Unlock( lock );
  2418.  
  2419.   lock:     (BPTR) Actually a pointer to FileLock structure
  2420.             which has been initialized by a previous Lock()
  2421.             call.
  2422.  
  2423.  
  2424.  
  2425. Write()
  2426.  
  2427.   This function writes a specified number of bytes to a file.
  2428.  
  2429.   Synopsis:  bytes_wr = Write( file_handle, buffer, size );
  2430.  
  2431.   bytes_wr:    (long) Number of bytes actually written. Even if
  2432.                you tell AmigaDOS that you want to write x number
  2433.                of bytes, it is not certain that you actually
  2434.                can do it. Maybe the disk was full, write-
  2435.                protected etc.
  2436.  
  2437.   file_handle: (BPTR) Actually a pointer to a FileHandle
  2438.                structure which has been initialized by a
  2439.                previous Open() call.
  2440.  
  2441.   buffer:      (char *) Pointer to the data buffer which you
  2442.                want to write.
  2443.  
  2444.   size:        (long) Number of bytes you want to write.
  2445.